home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / IFC_112 / netscape / application / Image.java < prev    next >
Encoding:
Text File  |  1999-05-28  |  10.4 KB  |  314 lines  |  [TEXT/CWIE]
  1. // Image.java
  2. // By Ned Etcode
  3. // Copyright 1996, 1997 Netscape Communications Corp.  All rights reserved.
  4.  
  5. package netscape.application;
  6.  
  7. import netscape.util.*;
  8.  
  9.  
  10. /** Abstract Object subclass representing objects that have an intrinsic
  11.   * width and height and can draw themselves to a Graphics object. Bitmap and
  12.   * DrawingSequence are two concrete implementations of the abstract Image
  13.   * class. Many user interface elements take Images to customize their
  14.   * appearance. By implementing the three primitive Image methods, you can
  15.   * create custom Images and use them with any component that accepts Images.
  16.   * Image also provides several convenience methods for drawing itself
  17.   * centered, scaled and tiled.
  18.   */
  19.  
  20.  
  21. public abstract class Image implements Codable {
  22.     /** Display option that centers the Image within a rectangle. */
  23.     public static final int CENTERED = 0;
  24.  
  25.     /** Display option that scales the Image within a rectangle. */
  26.     public static final int SCALED = 1;
  27.  
  28.     /** Display option that tiles the Image within a rectangle. */
  29.     public static final int TILED = 2;
  30.  
  31.     /** Drag type.*/
  32.     public static final String IMAGE_TYPE = "netscape.application.Image";
  33.  
  34.  
  35.     /* static methods */
  36.  
  37.  
  38.     /** Returns the Image instance with name <b>name</b>.  This method
  39.       * assumes that <b>name</b> consists of an Image subclass name,
  40.       * followed by the Image's path, separated by a forward or backward
  41.       * slash.  For example, the name:
  42.       * <pre>
  43.       *     ImageSequence/myApp/Tire.anim
  44.       * </pre>
  45.       * describes an instance of class "ImageSequence" with the name
  46.       * "myApp/Tire.anim."  <b>imageNamed</b> locates the specified class,
  47.       * creates an instance of it, and calls its <b>imageWithName()</b> method,
  48.       * passing in the Image name (in this case, "myApp/Tire.anim").  Image
  49.       * subclasses should override the <b>imageWithName()</b> method to locate
  50.       * and return the requested Image by name.<p>
  51.       * <i><b>Note:</b> <b>imageNamed()</b> only calls Bitmap's
  52.       * <b>imageWithName()</b> method if <b>name</b> begins with "Bitmap."
  53.       * That is, it doesn't attempt to call the static <b>bitmapNamed()</b>
  54.       * method on Bitmap.  If you know that you're requesting a Bitmap, you
  55.       * should call <b>Bitmap.bitmapNamed()</b> explicitly.</i>
  56.       * @see #imageWithName
  57.       * @see Bitmap#bitmapNamed
  58.       * @private
  59.       */
  60.     public static Image imageNamed(String name) {
  61.         Class   theClass;
  62.         Image   theImage;
  63.         String  typeName, className = "";
  64.         int     slash;
  65.  
  66.         slash = name.indexOf('/');
  67.         if (slash == -1) {
  68.             slash = name.indexOf('\\');
  69.         }
  70.  
  71.         if (slash == -1) {
  72.             return null;
  73.         }
  74.  
  75.         typeName = name.substring(0, slash);
  76.  
  77.         try {
  78.             className = "netscape.application." + typeName;
  79.             theClass = Class.forName(className);
  80.         } catch (ClassNotFoundException e) {
  81.             theClass = null;
  82.         }
  83.  
  84.         if (theClass == null) {
  85.             try {
  86.                 className = typeName;
  87.                 theClass = Class.forName(typeName);
  88.             } catch (ClassNotFoundException e) {
  89.                 theClass = null;
  90.             }
  91.         }
  92.  
  93.         if (theClass == null) {
  94.             return null;
  95.         }
  96.  
  97.         try {
  98.             theImage = (Image)theClass.newInstance();
  99.         } catch (InstantiationException e) {
  100.             throw new InconsistencyException("Unable to instantiate class \"" +
  101.                                          className + "\" -- " +
  102.                                          e.getMessage());
  103.         } catch (IllegalAccessException e) {
  104.             throw new InconsistencyException("Illegal access to class \"" +
  105.                                          className + "\" -- " +
  106.                                          e.getMessage());
  107.         }
  108.  
  109.         return theImage.imageWithName(name.substring(slash + 1));
  110.     }
  111.  
  112.     /** Returns the Image's width.  Subclassers must implement this method
  113.       * to return the subclass instance's width.
  114.       */
  115.     public abstract int width();
  116.  
  117.     /** Returns the Image's height.  Subclassers must implement this method
  118.       * to return the subclass instance's height.
  119.       */
  120.     public abstract int height();
  121.  
  122.     /** Draws the Image at the given location.  Subclassers must implement
  123.       * this method to draw the subclass instance using the Graphics <b>g</b>.
  124.       */
  125.     public abstract void drawAt(Graphics g, int x, int y);
  126.  
  127.     /** Draws the Image scaled to fit the supplied rectangle.  This method
  128.       * will not correctly scale most Image subclasses.  In cases where this
  129.       * method produces incorrect scaling, subclassers should override and
  130.       * implement their own scaling algorithm.
  131.       */
  132.     public void drawScaled(Graphics g, int x, int y, int width, int height) {
  133.         drawCentered(g, x, y, width, height);
  134.     }
  135.  
  136.     /** Returns the Image's name.  Default implementation returns <b>null</b>.
  137.       * Subclassers should override to return the Image's name.
  138.       */
  139.     public String name() {
  140.         return null;
  141.     }
  142.  
  143.     /** Draws the Image centered in the supplied rectangle.  Computes a
  144.       * location and calls <b>drawAt()</b>.
  145.       */
  146.     public void drawCentered(Graphics g, int x, int y, int width, int height) {
  147.         drawAt(g, x + (width - width()) / 2, y + (height - height()) / 2);
  148.     }
  149.  
  150.     /** Draws the Image centered in the Rect <b>rect</b>.  Calls the primitive
  151.       * <b>drawCentered()</b>.
  152.       * @see #drawCentered(Graphics, int, int, int, int)
  153.       */
  154.     public void drawCentered(Graphics g, Rect rect) {
  155.         if (rect == null)
  156.             return;
  157.  
  158.         drawCentered(g, rect.x, rect.y, rect.width, rect.height);
  159.     }
  160.  
  161.     /** Draws the Image scaled in the Rect <b>rect</b>.  Calls the primitive
  162.       * <b>drawScaled()</b>.
  163.       * @see #drawScaled(Graphics, int, int, int, int)
  164.       */
  165.     public void drawScaled(Graphics g, Rect rect) {
  166.         if (rect == null)
  167.             return;
  168.  
  169.         drawScaled(g, rect.x, rect.y, rect.width, rect.height);
  170.     }
  171.  
  172.     /** Draws the Image tiled in the supplied rectangle.  Calls
  173.       * <b>drawAt()</b> for each tile.
  174.       */
  175.     public void drawTiled(Graphics g, int x, int y, int width, int height) {
  176.         Rect clipRect;
  177.         int imageWidth, imageHeight, minX, minY, maxX, maxY;
  178.  
  179.         clipRect = g.clipRect();
  180.         imageWidth = width();
  181.         imageHeight = height();
  182.  
  183.         if (imageWidth <= 0 || imageHeight <= 0)
  184.             return;
  185.  
  186.         g.pushState();
  187.         g.setClipRect(new Rect(x, y, width, height));
  188.  
  189.         if (x > clipRect.x)
  190.             minX = x;
  191.         else
  192.             minX = x + imageWidth * ((clipRect.x - x) / imageWidth);
  193.  
  194.         if ((x + width) < clipRect.maxX())
  195.             maxX = x + width;
  196.         else
  197.             maxX = clipRect.maxX();
  198.  
  199.         if (y > clipRect.y)
  200.             minY = y;
  201.         else
  202.             minY= y + imageHeight * ((clipRect.y - y) / imageHeight);
  203.  
  204.         if ((y + height) < clipRect.maxY())
  205.             maxY = (y + height);
  206.         else
  207.             maxY = clipRect.maxY();
  208.  
  209.         for (x = minX; x < maxX; x += imageWidth) {
  210.             for (y = minY; y < maxY; y += imageHeight) {
  211.                 drawAt(g, x, y);
  212.             }
  213.         }
  214.  
  215.         g.popState();
  216.     }
  217.  
  218.     /** Draws the Image tiled in the Rect <b>rect</b>.  Calls the primitive
  219.       * <b>drawTiled()</b>.
  220.       * @see #drawTiled(Graphics, int, int, int, int)
  221.       */
  222.     public void drawTiled(Graphics g, Rect rect) {
  223.         if (rect == null)
  224.             return;
  225.  
  226.         drawTiled(g, rect.x, rect.y, rect.width, rect.height);
  227.     }
  228.  
  229.     /** Calls <b>drawCentered()</b>, <b>drawScaled()</b>, or
  230.       * <b>drawTiled()</b> based on the <b>style</b> parameter.  <b>style</b>
  231.       * can be one of CENTERED, SCALED or TILED.
  232.       */
  233.     public void drawWithStyle(Graphics g, int x, int y, int width, int height,
  234.                               int style) {
  235.  
  236.         switch (style) {
  237.             case CENTERED:
  238.                 drawCentered(g, x, y, width, height);
  239.                 break;
  240.             case SCALED:
  241.                 drawScaled(g, x, y, width, height);
  242.                 break;
  243.             case TILED:
  244.                 drawTiled(g, x, y, width, height);
  245.                 break;
  246.             default:
  247.                 throw new InconsistencyException("Unknown style: " + style);
  248.         }
  249.     }
  250.  
  251.     /** Convenience method for calling <b>drawWithStyle()</b> with Rect
  252.       * <b>rect</b>. Equivalent to the code:
  253.       * <pre>
  254.       *     drawWithStyle(g, rect.x, rect.y, rect.width, rect.height, style).
  255.       * </pre>
  256.       * @see #drawWithStyle(Graphics, int, int, int, int, int)
  257.       */
  258.     public void drawWithStyle(Graphics g, Rect rect, int style) {
  259.         drawWithStyle(g, rect.x, rect.y, rect.width, rect.height, style);
  260.     }
  261.  
  262.     /** Called by the static <b>imageNamed()</b> method to retrieve the Image
  263.       * with name <b>name</b>.  This method returns <b>null</b>.  Subclassers
  264.       * should override this method and implement it such that it locates
  265.       * and returns the requested Image.
  266.       * @private
  267.       * @see Image#imageNamed
  268.       */
  269.     public Image imageWithName(String name) {
  270.         return null;
  271.     }
  272.  
  273.     /** Returns <B>true</B> if the Image is transparent. Images are assumed
  274.       * to be transparent unless the subclass overrides this method. Returning
  275.       * <b>true</b> is always safe, but an Image user may
  276.       * be able to avoid drawing the region under the Image if this method
  277.       * returns <b>false</b>.
  278.       */
  279.     public boolean isTransparent() {
  280.         return true;
  281.     }
  282.  
  283.     // The coding methods are here just for convenience.  Stateless Image
  284.     // subclasses won't need to implement these stubs.
  285.  
  286.     /** Defined so that Images are Codable.  Stateless Images need not
  287.       * implement.
  288.       * @see Codable#describeClassInfo
  289.       */
  290.     public void describeClassInfo(ClassInfo info) {
  291.     }
  292.  
  293.     /** Defined so that Images are Codable.  Stateless Images need not
  294.       * implement.
  295.       * @see Codable#encode
  296.       */
  297.     public void encode(Encoder encoder) throws CodingException {
  298.     }
  299.  
  300.     /** Defined so that Images are Codable.  Stateless Images need not
  301.       * implement.
  302.       * @see Codable#decode
  303.       */
  304.     public void decode(Decoder decoder) throws CodingException {
  305.     }
  306.  
  307.     /** Defined so that Images are Codable.  Stateless Images need not
  308.       * implement.
  309.       * @see Codable#finishDecoding
  310.       */
  311.     public void finishDecoding() throws CodingException {
  312.     }
  313. }
  314.